31.15.6 Customizing the Diary

Ordinarily, the diary window indicates any holidays that fall on the date of the diary entries, either in the mode line or the buffer itself. The process of checking for holidays can be slow, depending on the defined holidays. In that case, setting diary-show-holidays-flag to nil will speed up the diary display.

The variable diary-number-of-entries controls the number of days of diary entries to be displayed at one time. It affects the initial display when calendar-view-diary-initially-flag is t, as well as the command M-x diary. For example, a value of 1 (the default) displays only the current day’s diary entries, whereas a value of 2 will also show the next day’s entries. The value can also be a vector of seven integers: for example, if the value is [0 2 2 2 2 4 1] then no diary entries appear on Sunday, the current date’s and the next day’s diary entries appear Monday through Thursday, Friday through Monday’s entries appear on Friday, while on Saturday only that day’s entries appear.

You can customize the form of dates in your diary file by setting the variable diary-date-forms. This variable is a list of patterns for recognizing a date. Each date pattern is a list whose elements may be regular expressions (see Regular Expressions in the Emacs Lisp Reference Manual) or the symbols month, day, year, monthname, and dayname. All these elements serve as patterns that match certain kinds of text in the diary file. In order for the date pattern as a whole to match, all of its elements must match consecutively.

A regular expression in a date pattern matches in its usual fashion, using the standard syntax table altered so that ‘*’ is a word constituent.

The symbols month, day, year, monthname, and dayname match the month number, day number, year number, month name, and day name of the date being considered. The symbols that match numbers allow leading zeros; those that match names allow capitalization and abbreviation (as specified by calendar-month-abbrev-array and calendar-day-abbrev-array). All the symbols can match ‘*’; since ‘*’ in a diary entry means “any day”, “any month”, and so on, it should match regardless of the date being considered.

The default value of diary-date-forms in the American style is provided by diary-american-date-forms:

((month "/" day "[^/0-9]")
 (month "/" day "/" year "[^0-9]")
 (monthname " *" day "[^,0-9]")
 (monthname " *" day ", *" year "[^0-9]")
 (dayname "\\W"))

The variables diary-european-date-forms and diary-iso-date-forms provide other default styles.

The date patterns in the list must be mutually exclusive and must not match any portion of the diary entry itself, just the date and one character of whitespace. If, to be mutually exclusive, the pattern must match a portion of the diary entry text—beyond the whitespace that ends the date—then the first element of the date pattern must be backup. This causes the date recognizer to back up to the beginning of the current word of the diary entry, after finishing the match. Even if you use backup, the date pattern must absolutely not match more than a portion of the first word of the diary entry. For example, the default value of diary-european-date-forms is:

((day "/" month "[^/0-9]")
 (day "/" month "/" year "[^0-9]")
 (backup day " *" monthname "\\W+\\<\\([^*0-9]\\|\\([0-9]+[:aApP]\\)\\)")
 (day " *" monthname " *" year "[^0-9]")
 (dayname "\\W"))

Notice the use of backup in the third pattern, because it needs to match part of a word beyond the date itself to distinguish it from the fourth pattern.